.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2025 grommunio GmbH
.TH ldap_adaptor 4gx "" "Gromox" "Gromox admin reference"
.SH Name
ldap_adaptor \(em LDAP connector for authentication
.SH Description
ldap_adaptor is a component for Gromox that facilitates the use of an LDAP
server for authentication purposes. Since the authoritative user database is in
MySQL, LDAP is only used to perform authentication (Bind operations), and
metadata searches that lead up to such Binds, i.e. looking for the LDAP object
that has a particular "mail" attribute.
.PP
Gromox versions 1.33 and onwards have support for using different LDAP servers
per organization. The SQL database for Gromox users (and domains and organizations)
has room to store properties on the individual organization objects. Use
Grommunio AAPI/AWEB to create and/or change organizations and their properties.
These properties from SQL can selectively override the six config directives
ldap_host, ldap_start_tls, ldap_bind_user, ldap_bind_pass, ldap_search_base and
ldap_mail_attr.
.SH Configuration directives
The configuration file, /etc/gromox/ldap_adaptor.cfg, serves not only the
ldap_adaptor component, but is also read by the Grommunio Admin API.
.SS Gromox directives
.TP
\fBauth_connections\fP
The maximum size of the connection pool for authentication requests. This
parameter has fixed value (same as data_connections) and is currently not
settable!
.br
(Authentication operations incur an implicit logout of whatever identity was
used before, which could incur extra latency if authentication operations and
metadata lookups were to be done on the same connection, which is why
ldap_adaptor has two separate connection pools.)
.br
Default: (same as data_connections)
.TP
\fBdata_connections\fP
The number of LDAP connections that will be kept active to the LDAP server for
the purpose of metadata searches.
.br
Default: \fI4\fP
.TP
\fBldap_edirectory_workarounds\fP
Attempt to deal with wire protocol violations brought about by Novell/NetIQ
eDirectory server implementations.
.br
Default: \fIfalse\fP
.TP
\fBldap_bind_user\fP
An LDAP binddn to use for metadata searches. You can only use Simple
Authentication at this time. If an organization object defines LDAP credentials
of its own, those will be used in preference to ldap_bind_user.
.br
Default: (unset)
.TP
\fBldap_bind_pass\fP
Password for Simple Authentication of ldap_bind_user.
.br
Default: (unset)
.TP
\fBldap_host\fP
Whitespace-separated set of LDAP URIs in the form of
\fIldap[si]://[name[:port]]\fP for the default LDAP tree. The openldap2
ldap.conf(5) manpage does not
specify trailing slashes or DN bases like RFC 2255 does, and because of this,
you should not use them. openldap2 utilities accept-ignore such part of the
URI, while other implementations like python\-ldap3 fail to connect.
Per-organization LDAP credentials override ldap_host as necessary.
.br
Default: (libldap default, see ldap.conf(5))
.TP
\fBldap_mail_attr\fP
The name of the LDAP attribute which holds the primary e-mail address of the
user. Pick \fBmail\fP (OpenLDAP as well as Active Directory schemes).
.br
Default: (empty)
.TP
\fBldap_search_base\fP
Default: (libldap default)
.TP
\fBldap_start_tls\fP
Use the STARTTLS mechanism on LDAP connections. Prefer using Explicit TLS
(ldaps:// in the URI field) in favor of ldap:// with STARTTLS; see Internet
blog posts "STARTTLS considered harmful" for details.
.br
Default: \fIoff\fP
.br
Take note that libldap may reject self-signed certificates from the LDAP
server. This may be worked around with the "TLS_REQCERT allow" directive in
ldap.conf. See the ldap.conf(5) manpage for details. However, by its
description, TLS_REQCERT will also make encryption optional, which means
becoming the victim of a downgrade attack is a possibility.
.SS Grommunio Admin API directives
.TP
\fBldap_host\fP
.PP
.TP
\fBldap_bind_user\fP
.PP
.TP
\fBldap_bind_pass\fP
.PP
.TP
\fBldap_search_base\fP
.PP
.TP
\fBldap_start_tls\fP
.PP
.TP
\fBldap_mail_attr\fP
(These six as above)
.TP
\fBldap_disabled\fP
If true, Grommunio Admin API will not make use of LDAP (which generally just
means synchronization). This directive has no effect on Gromox; users which
have been synchronized previously and which exist in MySQL keep their validity
as far as Gromox is concerned.
.TP
\fBldap_object_id\fP
The name of the LDAP attribute which holds a unique, unchanging object
identifier for synchronization purposes. Pick \fBentryUUID\fP for OpenLDAP,
\fBobjectGUID\fP for Active Directory.
.br
Default: (empty)
.TP
\fBldap_user_filter\fP
An LDAP search filter that specifies which users should be synchronized.
Recommendations are \fB(objectClass=posixAccount)\fP for OpenLDAP/RFC2307bis,
\fB(objectClass=user)\fP for Active Directory.
.br
Default: (empty)
.TP
\fBldap_user_displayname\fP
The name of the LDAP attribute which holds the value for PR_DISPLAY_NAME. Pick
\fBdisplayName\fP (OpenLDAP as well as Active Directory schemes).
.br
Default: (empty)
.TP
\fBldap_user_search_attrs\fP
The name(s) of LDAP attributes which the Admin API will compare when using
AAPI's search function. To specify multiple attributes, repeat this directive,
and specify one attribute per line, i.e. put \fIldap_user_search_attrs=mail\fP
and \fIldap_user_search_attrs=cn\fP, etc. in the config file.
.br
Default: (empty set)
.TP
\fBldap_user_template\fP
The name(s) of Admin API templates to use. Multi-value directive like
search_attrs. Pick \fBldap_user_template=common\fP and
\fBldap_user_template=OpenLDAP\fP for OpenLDAP, or
\fBldap_user_template=common\fP and \fPldap_user_template=ActiveDirectory\fP
for Active Directory.
.br
Default: (empty set)
.TP
\fBldap_user_aliases\fP
The name of the LDAP attribute which contains secondary e-mail addresses. Pick
\fBmailAlternativeAddress\fP (OpenLDAP) or \fBproxyAddresses\fP (Active
Directory). The \fBsmtp:\fP prefix in proxyAddresses is automatically trimmed
when read.
.br
Default: (empty)
.SH See also
\fBgromox\fP(7), \fBauthmgr\fP(4gx)
